/*
 * Copyright 2010-2012 Susanta Tewari. <freecode4susant@users.sourceforge.net>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package coalescent.br;

import java.util.TimerTask;

/**
 * Defines an interface for listeners that may want to trace the post-order recursion
 * implementation.<p>
 *
 * @param <E>
 * @param <S>
 * @author Susanta Tewari
 * @version 1.0 Dec 3, 2010
 */
public interface BRWComp<E extends Enum<E>, S extends AMCElement<E, S>> {

    /**
     * Invoked when boundary condition event occurs during the traversal of the recursion.
     *
     * @param event exact recursion event
     */
    void onBoundaryCondn(BRWCompInfo<E, S> event);

    /**
     * invoked when iteration of the ancestral configs are about to start during the traversal
     * of the recursion.
     *
     * @param event exact recursion event
     */
    void onStartingIteratingEvents(BRWCompInfo<E, S> event);

    /**
     * Invoked when iteration of the event types for a sample configuration are about to start
     * during the traversal of the recursion.
     *
     * @param event exact recursion event
     */
    void onIteratingSingleEventTypes(BRWCompInfo<E, S> event);

    /**
     * Invoked when an event occurs while iterating the ancestral configs during the traversal
     * of the recursion.
     *
     * @param event exact recursion event
     */
    void onIteratingAncestralConfigs(BRWCompInfo<E, S> event);

    /**
     * Invoked when iteration of the event types for a sample configuration are about to start
     * during the traversal of the recursion.
     *
     * @param event exact recursion event
     */
    void onFinishedIteratingSingleEventTypes(BRWCompInfo<E, S> event);

    /**
     * Invoked right after all the events for the sample config are processed.
     *
     * @param event exact recursion event
     */
    void onFinishedIteratingEvents(BRWCompInfo<E, S> event);

    /**
     * Invoked when iteration-finished event occurs during the traversal of the recursion.
     *
     * @param event exact recursion event
     */
    void onFinishedIteration(BRWCompInfo<E, S> event);

    /**
     * A timer task that shows intermediate results in the middle of the recursion.
     *
     * @return a timer task to show intermediate results or {@code null} if no such timer task is
     *         to be provided
     */
    TimerTask createTimerTask();

    /**
     * an update on the listener`s computation
     *
     * @return an update on the listener`s computation or {@code null} to indicate none is
     *         available or provided.
     */
    String getUpdateChunk();
}
